❌ Deploy Preview for scientific-python-hugo-theme failed.

Built without sensitive environment variables

The proposed change, i.e.

{{< figure
    src = "https://images.unsplash.com/photo-1546238232-20216dec9f72"
    alt = "Cute puppies"
    attribution = "Figure Credits: Cute puppies image from unsplash.com"
    attributionlink = "https://images.unsplash.com/photo-1546238232-20216dec9f72"
    align = "right"
    height = 150
    width = 150
    caption = "A figure with right alignment."
>}}

{{< /figure >}}

is working well on https://deploy-preview-674--scientific-python-hugo-theme.netlify.app/shortcodes/#figure 🐶

One last comment: I don't think we need the closing figure tags?

Hi @stefanv, I think @agriyakhetarpal tried to work on that too but there were some issues.

This change looks good to me.

We could also only support named parameters, we'd just need to fix up numpy.org, scipy.org, and all the SP websites. But, this is fine for now.

Hi @stefanv, thank you for the review! Yes, I considered supporting only named parameters, but opted not to to preserve backwards compatibility.

One last comment: I don't think we need the closing figure tags?

Hi @stefanv, I think @agriyakhetarpal tried to work on that too but there were some issues.

Yes – I tried to make it work without closing figure tags, but I had an issue with the HTML character entities not being converted to their symbol counterparts (such as &#34 for " and /&gt for >, and so on), as they were being rendered literally and breaking the shortcode, so I thought of leaving it so for now. I would be happy to explore this as a follow-up.

In the meantime, I've changed some more previously broken links for the cute puppies. I've confirmed that the image I used is free to use under the Unsplash license. :)

Yes – I tried to make it work without closing figure tags, but I had an issue with the HTML character entities not being converted to their symbol counterparts (such as &#34 for " and /&gt for >, and so on), as they were being rendered literally and breaking the shortcode, so I thought of leaving it so for now. I would be happy to explore this as a follow-up.

If we are going to introduce a new syntax, it would be nice to have it "done and dusted" in one go. Do you think it would take long to explore whether we could use {{< figure param=... /> }}?

In the meantime, I've changed some more previously broken links for the cute puppies. I've confirmed that the image I used is free to use under the Unsplash license. :)

I happened to check that too earlier today ;)

If we are going to introduce a new syntax, it would be nice to have it "done and dusted" in one go. Do you think it would take long to explore whether we could use {{< figure param=... /> }}?

Yes, this is what's broken. I'll take a look, though!

I wonder if the closing tag is required because we access .Inner? Or is .Inner only available when there is a closing tag? (That's be a bit odd.)

I think if that is the issue (using .Inner) then we should opt for the new version only.

Yes, that's indeed the case (@goanpeca and I were discussing this yesterday). I'm trying to see if we can make it work without it!

Okay, yeah, I don't think this is going to work, based on what I understand from https://discourse.gohugo.io/t/what-is-meant-by-closed-or-self-closed/44785 and https://gohugo.io/templates/shortcode/#inner. .Inner is available only with a closing tag, and its length is 0 with a self-closing tag.

I think we could:

• create a figure-single.html to handle the self-closing syntax specifically that would simply collect parameters and pass them to the regular figure shortcode as a partial, but that would be a new shortcode and I think it would confuse users.
  • maybe, we could rename the current figure.html to figure-base.html (and not document the figure-base shortcode), go ahead with this solution, and name that figure.html? It could work as nothing would be exposed to the user, but I think it confuses maintainers down the line.
• The other way is to use Hugo's own figure shortcode and adapt it to include the extra parameters we have as the self-closing syntax works there – but that breaks compatibility.

I would probably opt for none of these at the moment, at least for this PR :)

Having two syntaxes is confusing. Let's just move over to the newly proposed tag, make sure the change is mentioned in the release notes, and port the other websites that depend on it (there aren't that many).

(If, that is, I understood correctly that removing .Inner will fix the problem.)

Having two syntaxes is confusing. Let's just move over to the newly proposed tag, make sure the change is mentioned in the release notes, and port the other websites that depend on it (there aren't that many).

(If, that is, I understood correctly that removing .Inner will fix the problem.)

Yes, I get this, but I think it would also be odd to have just the {{< figure >}} shortcode with the new named parameters syntax + dropping .Inner to support self-closing tags for it, and not any of the other shortcodes that are also using .Inner? Should I aim to port the rest of them, too? If we do, then it breaks a lot more content downstream (which I have no issues fixing, though!).

Edit: oh yes, it doesn't break things immediately though, as I think most websites use the theme as a submodule. It'd happen when they update to the new release where this is included.

I suspect you're going to run into issues with some of the other shortcodes, such as cards.

But, I think you are right that we should be consistent.

Can we use the same pattern as here to make inline/in-body usage possible for those?

Yes, I think it should be possible. I think we can also keep it as is for shortcodes that are tricky to port or where it doesn't make sense to change. For example, the admonition shortcode:

{{< admonition hint >}}
This is an hint admonition.
{{< /admonition >}}

seems perfectly fine to me, as {{< admonition hint "This is an hint admonition." />}} looks a little off, and would not work for complex uses where someone may want a mixture of multiline strings + images + tables, and whatnot within the admonition... This is an example where the current one works well.

Here's a list of the shortcodes that I think can be ported:

1. button:

It would go from

{{< button success >}}
label: Success
link: http://example.com/
{{< /button >}}

to

{{< button success label = "Success" link = "http://example.com/" />}}

Similarly,

2. Dropdown (edit: removed this on 14/05/2025)
3. Image

The ones I think are fine as is:

1. Admonition
2. Card
3. Dropdown (as it's possible to use multiline strings + images + complex Markdown)
4. Details
5. Field List (uses TOML tables)
6. Grid (same as Field List)
7. Sidebar (as it supports nested shortcodes based on the provided example)
8. Tabs

The ones below don't use .Inner at all currently and are thus fine as is:

1. include-code
2. include-html
3. include-md
4. include-raw
5. include
6. toctree

I can port the button, dropdown, and the image shortcodes, unless you suggest otherwise! Another option is to just port figure and image for now, as both of them are closely related in terms of functionality.

Yes, I think the rule would be: anything that calls for parameters in the body, we can port. With the exception of cards, because those parameters are actually content 🙄 😬

I'll finish up later today, thanks!

Having two syntaxes is confusing. Let's just move over to the newly proposed tag, make sure the change is mentioned in the release notes

Indeed it might be better to have just one. Thanks for the commentary and suggestions @stefanv!

I wanted to ask if we could limit the scope of the PR to what @agriyakhetarpal initially worked on and in a subsequent PR make all the additional changes.

We (quansight) are finishing the work for the scientific python translations grant and it would help of we can deploy numpy.org soonish which is currently blocked due to some issues with crowdin (the translations platform) not understanding the current shortcode syntax for figures and stripping all the content away.

I have already migrated the numpy figures over at numpy/numpy.org#859

I can help migrating other sites as well.

Hi @goanpeca, I think we should forego the changes to the "dropdown" shortcode; I think we made an oversight. In another PR that I was working on just now (#675), I noticed that dropdowns can have content in the body parameter, which doesn't make sense to inline as inline parameters are not processed – which means that if one were to add something like a code block or a complex multiline string, it wouldn't work well.

Originally, in #674 (comment), I made the mistake where I added the "dropdown" shortcode to both headings – in the "ones to modify" and "those to keep as-is", when we should have kept it only in the as-is heading 😅 I've updated that comment, as I think it was the cause of some confusion! Similar to Stefan's comment in #674 (comment) about cards, one of the parameters to the dropdown(s) is actually content, too.

I converted the PR to a draft again so that I can undo these changes specifically, so that we support inline parameters for only the image, figure, and button shortcodes, and I will update the PR description, etc., again.

Hello team, I created PRs with the updated syntax in preparation for these changes.

• scipy: Update shortcodes scipy/scipy.org#648
• numpy: Update the use of inline shortcodes (figure, image, button) numpy/numpy.org#859
• pybann: Update figure shortcodes to new syntax pybamm-team/pybamm.org#283
• learn.scientific-python.org: no changes needed.
• scientific-python.org: Update shortcodes scientific-python.org#768
• tools.scientific-python.org: Update shortcodes tools.scientific-python.org#72
• blog.scientific-python.org: no changes needed.
• devstats.scientific-python.org: no changes needed.
• specs.scientific-python.org: Update shortcodes specs#394

Thanks for all of the downstream PRs, @goanpeca! I went through all of them, and all of them work as advertised (with the updated theme, of course). We should now be in a good position to update all the websites with minimal turnaround, and I assume we can also update the theme submodule in those PRs themselves as soon as this PR is merged into a new v0.22 release.

@stefanv, this should be ready for another look; whenever it is convenient for you to do so. Thank you! :)

Looks good to me, overall.

It may be worth adding a note for developers on when to use keywords and when to use TOML in the body.

Thanks for the review! I'm afraid I don't understand this, though – could you please clarify? Do you mean we should highlight the shortcodes that will use the new syntax, and the ones that will stick to the old one?

Thanks for the review! I'm afraid I don't understand this, though – could you please clarify? Do you mean we should highlight the shortcodes that will use the new syntax, and the ones that will stick to the old one?

I meant guidance for developers; but it's fine, we don't really have a component developer guide.

Build error seems related.

Yes, the builds will fail (xref: #674 (comment), #674 (comment)) as the tests build the SciPy website in CI. They will pass here when scipy/scipy.org#648 is merged (it requires the theme submodule bump).

Here is a list of @goanpeca's PRs for all downstream websites: #674 (comment)

P.S. I wonder if we could make our downstream testing easier with Pixi tasks. It's surely worth an experiment...

Thanks for the review! I'm afraid I don't understand this, though – could you please clarify? Do you mean we should highlight the shortcodes that will use the new syntax, and the ones that will stick to the old one?

I meant guidance for developers; but it's fine, we don't really have a component developer guide.

Got it! I'll try to write something in a new PR. Based on this comment, I assume you're saying it's alright to defer doing so to v23 :)

Yes, we should try the pixi experiment!

Re: developer guidelines also see #616

Thanks, I think we're good to go here then, and to tag a new release! 🎉

@goanpeca, we'll release v0.22 in a while (finally!). When you get a chance, could you please rebase the downstream PRs for all the website and bump the theme version in them? Thank you!